@nshaw, is this the Kubernetes credentials? Am unsure about how to phrase the distinction between default-sso-in-namespace-admin-secret creds and the Keycloak admin user creds

@jyunmitch good catch, no, it's just the admin credentials which can be found in the corresponding k8s secret. "To find the Kubernetes credentials" -> "To find the admin credentials for Keycloak"

@nshaw, was trying to avoid "admin" credentials because that is used below in the Swagger authorization steps below (Access APIs on Swagger #4) for the Keycloak admin user (admin/adminadmin) and I wanted to try to distinguish the two

@jyunmitch Hmm. "Keycloak admin user" != "admin/adminadmin". "admin" is the Entando Application admin user. "entando_keycloak_admin" is the Keycloak admin user. Neither of them are Kubernetes users or credentials. Not sure that helps. :(

1st sentence: would reorder to set the reader up to easily follow this statement - starting with "what" and the env "what" applies to and then adding detail: "For API access in a quickstart environment, Entando includes the Swagger UI."

2nd sentence: "for Entando APIs" is a little redundant; is there a distinction between APIs (first sentence) and Entando APIs (second sentence)? i read this as being repetitive because there is a difference and the second sentence specifies a use case

1st sentence: 'For API access in a quickstart environment' >> there isn't a reference for what a quickstart environment is when the sentence is ordered this way. Left it as is

not sure i understand your comment; neither version of the sentence provides a reference or context for what the quickstart env is... rereading i think i like the original better tho anyway.

in terms of defining the quickstart env, isn't this the env you configure when you follow our getting started guides? we reference the quickstart env often and it's not explicitly defined anywhere, so i think maybe we should think about doing that. linking to that can be done as necessary when we revisit pages, or in a separate ticket to hit all the mentions

In this version: 'For API access in a quickstart environment,...' the quickstart enve has no reference point, whereas starting with Entando gives it the reference that it's an Entando environment

we don't often refer to "the Entando core"... can we put this in more familiar language (even with a link) by specifying what the core is? the app engine? like when we talk about what composes Entando we don't list the Core, right?

"every action that can be taken in" sounds a bit odd... "every action available in"?

also 2nd sentence: the structure presumes 3 things that can be created, so it's halting to realize "create" only applies to the first two entities, then the verb switches to "add"; "For example, you can use APIs to create pages and page templates or add widgets to pages." another option is to just list one example for "create" to avoid another and, or or comma

3rd sentence: "as well" tacked on to the end is a bit awkward and deemphasizes that this sentence is listing additional API capabilities: "In addition, the APIs can be used to...external systems."

This was what was there and I don't know the specifics enough to edit this. Played with it just a bit.

"All of" - more formal/complete

top-level is hyphenated (modifier)

'All of' changes the meaning>> it changes the sharing to something between the APIs as opposed to sharing a characteristics

i don't understand this comment. can you rephrase to clarify?

All of the APIs share a common ...> makes it sound like they all share something together, not have something in common.

as an example, "all the kids eat cake" vs "all of the kids eat cake"; neither clarifies whether they're eating the same cake (sharing something together) or their own cakes (have eating cake in common). not worth pursuing

the first sentence is a bit hard to interpret without rereading, but switching the structure would help: "An error condition in the request will return the code that was unable to execute and one or more error messages."

second sentence: odd because i expect a fourth action to follow paging, sorting and filtering, but instead a noun is listed; the absence of what those verbs are acting on makes me think that there was a typo and the and in and data shouldn't be there

the third sentence really confuses me: the body of the response is included...in the response???

again, it was as is. Played with it a bit

The 'body' is a specific part of an API structure, i think it carries the main data in the request and is maybe the payload

aha. the repetition threw me. if this level of detail is necessary it's probably worth clarifying a bit

anyone looking at rest APIs would know what bodys are

not what i meant at all

like the "all of"

Entando core again...

i don't really know how to interpret the first sentence. maybe it's obvious if you're reading this as you work with the Swagger UI, but i have questions... is the annotation the model definition? and where is this info returned? in the Swagger UI? "Swagger documentation" makes me think like the manual on how to work with swagger

second sentence: "at the bottom of the page,..." (comma) but the "can be found" is a little oddly placed and not very necessary... "all of the model classes returned by the API endpoints are listed at the bottom of the Swagger page"

In APIs>>Annotations are like meta-tags that you can add to the code and apply to package declarations, type declarations, constructors, methods, fields, parameters, and variables.

seems like the models are templates/formats for data being returned, and the documentation includes annotation with definitions. Like one model included one string and one boolean data with the variable names. and this is included in a Get request Body for an API

another aha. your explanation connects the dots... if the first sentence can be modified to include the gist of that it would be worthwhile. like "All of the model classes for the data returned by the App Engine are annotated, with the annotations defined in the Swagger documentation." this is how i read your comment, which is a bit different from - and more clear than - the 1st sentence as-is

it's been changed already

notice that there are periods for single-sentence steps here (no periods used for single sentences in above steps)

this was the only one without in this list so it looked odd

same wrt period

Secret

ID should be capitalized unless it's the property itself, then should be backticked

its methods (not all methods are the same??)

methods are API thing, get post delete etc.

no no no, sorry - i mean do the same methods apply to all the APIs or do different APIs support different methods? if the same always apply then "the methods" is the way to go because there is only one set and it's used for every API - the specificity works. but if different APIs have different methods then "the" APIs is imprecise, but "its APIs" is specific

the way others talk about methods, they don't generally seem to talk about it that way. Each one may have different items and request things in it, but 'get' always works the same way so they talk about methods in a general way. 'its' methods sounds wrong

not sure what the GET method has to do with this? pretty sure most everyone would use "its"

methods in Rest APIs are specifically get, post, delete, etc and there's a limited list. It's not talking about methods in general

great. that clears it up

"The results are visible in the window below" or "view the results..." (a bit less aggressive and avoids a repeat of the word "see")

"see a Server response with Code 200 and full response body"... why is server capitalized? if code is capitalized "Code 200" should be in quotes to indicate that's the actual value you see (conversely code 200 implies you'll see just the number 200)

"You should see a Server response with Code 200 and full response body"... i feel like this could be rephrased for clarity and to avoid two "responses"

not sure why server was capped??
Code 200 is like Error 404, does it need backticks?? In this case, don't think it's necessary
edited

I actually prefer 'see the results..' it's direct and clear. view sounds too much like sightseeing.

i don't think backticks, only quotes because it's a name

we should def go for the sightseeing angle. maybe we could start selling merch ;)

It's not a name, it's a resultant code and in HTTP protocols, it's a common response that really doesn't need special citing

it's the name of a code. i'm fine with capitalized and no quotes, but we have quoted or otherwise formatted codes elsewhere in the documentation so this is more about consistency. should we say going forward to not format stuff like this? i actually think we should because it gets really busy with backticks/quotes and like you said, it's not necessary

here is Entando core again! are "entando" and "core" modifiers for "APIs" or is "Entando" modifying "core APIs"? like are we talking about the Entando core or core APIs? if the entando core is a thing we're referencing often we need to better define it in an intro page

no mention of "core" here: https://developer.entando.com/next/docs/getting-started/concepts-overview.html#key-entando-concepts

Not touching this one because it is the tutorial name and I think it refers to core in the sense that it's attached to the center of Entando which is the Engine. If we want to change that title, we can get a ticket for that. Core and engine are used interchangeably by the devs apparently

got rid of both next steps because the REST apis is going to be deleted anyways

or we could make a ticket for defining core somewhere in the docs... it appears here and there but is never defined

Client Id like in step 4??

trying to minimize backticking... here backticked client id is the same as the literal words client ID the term. I don't think there would be any confusion.

same comment

could enact -> execute? seems to be more precise and the usual language?

I think enact is fine here, especially as APIs don't really execute things as they just move information back and forth